<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Run a search | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="search-your-data.html" title="Search your data">
<link rel="prev" href="search-your-data.html" title="Search your data">
<link rel="next" href="near-real-time.html" title="Near real-time search">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="search-your-data.html">Search your data</a></span>
»
<span class="breadcrumb-node">Run a search</span>
</div>
<div class="navheader">
<span class="prev">
<a href="search-your-data.html">« Search your data</a>
</span>
<span class="next">
<a href="near-real-time.html">Near real-time search »</a>
</span>
</div>
<div class="chapter">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="run-a-search"></a>Run a search<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/run-a-search.asciidoc">edit</a>
</h2>
</div></div></div>
<p>You can use the <a class="xref" href="search-search.html" title="Search API">search API</a> to search data stored in
one or more Elasticsearch indices.</p>
<p>The API can runs two types of searches, depending on how you provide
<a class="xref" href="search-your-data.html#search-query">queries</a>:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<a class="xref" href="run-a-search.html#run-uri-search" title="Run a URI search">URI searches</a>
</span>
</dt>
<dd>
Queries are provided through a query parameter. URI searches tend to be
simpler and best suited for testing.
</dd>
<dt>
<span class="term">
<a class="xref" href="run-a-search.html#run-request-body-search" title="Run a request body search">Request body searches</a>
</span>
</dt>
<dd>
Queries are provided through the JSON body of the API request. These queries
are written in <a class="xref" href="query-dsl.html" title="Query DSL">Query DSL</a>. We recommend using request body
searches in most production use cases.
</dd>
</dl>
</div>
<div class="warning admon">
<div class="icon"></div>
<div class="admon_content">
<p>If you specify a query in both the URI and request body, the search API request
runs only the URI query.</p>
</div>
</div>
<h3>
<a id="run-uri-search"></a>Run a URI search<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/run-a-search.asciidoc">edit</a>
</h3>
<p>You can use the search API’s <a class="xref" href="search-search.html#search-api-query-params-q"><code class="literal">q</code> query string
parameter</a> to run a search in the request’s URI. The <code class="literal">q</code> parameter only accepts
queries written in Lucene’s <a class="xref" href="query-dsl-query-string-query.html#query-string-syntax" title="Query string syntax">query string syntax</a>.</p>
<details>
<summary class="title"><span class="strong strong"><strong>Example</strong></span></summary>
<div class="content">
<p>To get started, ingest or add some data to an Elasticsearch index.</p>
<p>The following <a class="xref" href="docs-bulk.html" title="Bulk API">bulk API</a> request adds some example user log data to
the <code class="literal">user_logs_000001</code> index.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /user_logs_000001/_bulk?refresh
{"index":{"_index" : "user_logs_000001", "_id" : "1"}}
{ "@timestamp": "2020-12-06T11:04:05.000Z", "user": { "id": "vlb44hny" }, "message": "Login attempt failed" }
{"index":{"_index" : "user_logs_000001", "_id" : "2"}}
{ "@timestamp": "2020-12-07T11:06:07.000Z", "user": { "id": "8a4f500d" }, "message": "Login successful" }
{"index":{"_index" : "user_logs_000001", "_id" : "3"}}
{ "@timestamp": "2020-12-07T11:07:08.000Z", "user": { "id": "l7gk7f82" }, "message": "Logout successful" }</pre>
</div>
<div class="console_widget" data-snippet="snippets/76.console"></div>
<p>You can now use the search API to run a URI search on this index.</p>
<p>The following URI search matches documents with a <code class="literal">user.id</code> value of <code class="literal">l7gk7f82</code>.
Note the query is specified using the <code class="literal">q</code> query string parameter.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /user_logs_000001/_search?q=user.id:8a4f500d</pre>
</div>
<div class="console_widget" data-snippet="snippets/77.console"></div>
<p>The API returns the following response. Note the <code class="literal">hits.hits</code> property contains
the document that matched the query.</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "took": 2,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.9808291,
    "hits": [
      {
        "_index": "user_logs_000001",
        "_type": "_doc",
        "_id": "2",
        "_score": 0.9808291,
        "_source": {
          "@timestamp": "2020-12-07T11:06:07.000Z",
          "user": {
            "id": "8a4f500d"
          },
          "message": "Login successful"
        }
      }
    ]
  }
}</pre>
</div>
</div>
</details>
<h3>
<a id="run-request-body-search"></a>Run a request body search<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/run-a-search.asciidoc">edit</a>
</h3>
<p>You can use the search API’s <a class="xref" href="search-search.html#request-body-search-query"><code class="literal">query</code> request
body parameter</a> to provide a query as a JSON object, written in
<a class="xref" href="query-dsl.html" title="Query DSL">Query DSL</a>.</p>
<details>
<summary class="title"><span class="strong strong"><strong>Example</strong></span></summary>
<div class="content">
<p>The following request body search uses the <a class="xref" href="query-dsl-match-query.html" title="Match query"><code class="literal">match</code></a>
query to match documents with a <code class="literal">message</code> value of <code class="literal">login successful</code>. Note the
<code class="literal">match</code> query is specified as a JSON object in the <code class="literal">query</code> parameter.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /user_logs_000001/_search
{
  "query": {
    "match": {
      "message": "login successful"
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/78.console"></div>
<p>The API returns the following response.</p>
<p>The <code class="literal">hits.hits</code> property contains matching documents. By default, the response
sorts these matching documents by <code class="literal">_score</code>, a <a class="xref" href="query-filter-context.html#relevance-scores" title="Relevance scores">relevance
score</a> that measures how well each document matches the query.</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "took": 1,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 3,
      "relation": "eq"
    },
    "max_score": 0.9983525,
    "hits": [
      {
        "_index": "user_logs_000001",
        "_type": "_doc",
        "_id": "2",
        "_score": 0.9983525,
        "_source": {
          "@timestamp": "2020-12-07T11:06:07.000Z",
          "user": {
            "id": "8a4f500d"
          },
          "message": "Login successful"
        }
      },
      {
        "_index": "user_logs_000001",
        "_type": "_doc",
        "_id": "3",
        "_score": 0.49917626,
        "_source": {
          "@timestamp": "2020-12-07T11:07:08.000Z",
          "user": {
            "id": "l7gk7f82"
          },
          "message": "Logout successful"
        }
      },
      {
        "_index": "user_logs_000001",
        "_type": "_doc",
        "_id": "1",
        "_score": 0.42081726,
        "_source": {
          "@timestamp": "2020-12-06T11:04:05.000Z",
          "user": {
            "id": "vlb44hny"
          },
          "message": "Login attempt failed"
        }
      }
    ]
  }
}</pre>
</div>
</div>
</details>
<h3>
<a id="search-multiple-indices"></a>Search multiple indices<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/run-a-search.asciidoc">edit</a>
</h3>
<p>To search multiple indices, add them as comma-separated values in the search API
request path.</p>
<details>
<summary class="title"><span class="strong strong"><strong>Example</strong></span></summary>
<div class="content">
<p>The following request searches the <code class="literal">user_logs_000001</code> and <code class="literal">user_logs_000002</code>
indices.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /user_logs_000001,user_logs_000002/_search
{
  "query": {
    "match": {
      "message": "login successful"
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/79.console"></div>
</div>
</details>
<p>You can also search multiple indices using an index pattern.</p>
<details>
<summary class="title"><span class="strong strong"><strong>Example</strong></span></summary>
<div class="content">
<p>The following request uses the index pattern <code class="literal">user_logs*</code> in place of the index
name. The request searches any indices in the cluster that start with
<code class="literal">user_logs</code>.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /user_logs*/_search
{
  "query": {
    "match": {
      "message": "login successful"
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/80.console"></div>
</div>
</details>
<p>To search all indices in a cluster, omit the index name from the request path.
Alternatively, you can use <code class="literal">_all</code> or <code class="literal">*</code> in place of the index name.</p>
<details>
<summary class="title"><span class="strong strong"><strong>Example</strong></span></summary>
<div class="content">
<p>The following requests are equivalent and search all indices in the cluster.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_search
{
  "query": {
    "match": {
      "message": "login successful"
    }
  }
}

GET /_all/_search
{
  "query": {
    "match": {
      "message": "login successful"
    }
  }
}

GET /*/_search
{
    "query" : {
        "match" : { "message" : "login" }
    }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/81.console"></div>
</div>
</details>
<h3>
<a id="paginate-search-results"></a>Paginate search results<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/request/from-size.asciidoc">edit</a>
</h3>
<p>By default, the search API returns the top 10 matching documents.</p>
<p>To paginate through a larger set of results, you can use the search API’s <code class="literal">size</code>
and <code class="literal">from</code> parameters. The <code class="literal">size</code> parameter is the number of matching documents
to return. The <code class="literal">from</code> parameter is a zero-indexed offset from the beginning of
the complete result set that indicates the document you want to start with.</p>
<details>
<summary class="title"><span class="strong strong"><strong>Example</strong></span></summary>
<div class="content">
<p>The following search API request sets the <code class="literal">from</code> offset to <code class="literal">5</code>, meaning the
request offsets, or skips, the first five matching documents.</p>
<p>The <code class="literal">size</code> parameter is <code class="literal">20</code>, meaning the request can return up to 20 documents,
starting at the offset.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_search
{
  "from": 5,
  "size": 20,
  "query": {
    "term": {
      "user.id": "8a4f500d"
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/82.console"></div>
</div>
</details>
<p>By default, you cannot page through more than 10,000 documents using the <code class="literal">from</code>
and <code class="literal">size</code> parameters. This limit is set using the
<a class="xref" href="index-modules.html#index-max-result-window"><code class="literal">index.max_result_window</code></a> index setting.</p>
<p>Deep paging or requesting many results at once can result in slow searches.
Results are sorted before being returned. Because search requests usually span
multiple shards, each shard must generate its own sorted results. These separate
results must then be combined and sorted to ensure that the overall sort order
is correct.</p>
<p>As an alternative to deep paging, we recommend using
<a class="xref" href="search-request-body.html#request-body-search-scroll" title="Scroll">scroll</a> or the
<a class="xref" href="search-request-body.html#request-body-search-search-after" title="Search After"><code class="literal">search_after</code></a> parameter.</p>
<div class="warning admon">
<div class="icon"></div>
<div class="admon_content">
<p>Elasticsearch uses Lucene’s internal doc IDs as tie-breakers. These internal
doc IDs can be completely different across replicas of the same
data. When paginating, you might occasionally see that documents with the same
sort values are not ordered consistently.</p>
</div>
</div>
<h3>
<a id="search-fields"></a>Retrieve selected fields<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/search-fields.asciidoc">edit</a>
</h3>
<p>By default, each hit in the search response includes the document
<a class="xref" href="mapping-source-field.html" title="_source field"><code class="literal">_source</code></a>, which is the entire JSON object that was
provided when indexing the document. If you only need certain source fields in
the search response, you can use the <a class="xref" href="run-a-search.html#source-filtering" title="Source filtering">source filtering</a> to
restrict what parts of the source are returned.</p>
<p>Returning fields using only the document source has some limitations:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
The <code class="literal">_source</code> field does not include <a class="xref" href="multi-fields.html" title="fields">multi-fields</a> or
<a class="xref" href="alias.html" title="Alias datatype">field aliases</a>. Likewise, a field in the source does not contain
values copied using the <a class="xref" href="copy-to.html" title="copy_to"><code class="literal">copy_to</code></a> mapping parameter.
</li>
<li class="listitem">
Since the <code class="literal">_source</code> is stored as a single field in Lucene, the whole source
object must be loaded and parsed, even if only a small number of fields are
needed.
</li>
</ul>
</div>
<p>To avoid these limitations, you can:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
Use the <a class="xref" href="run-a-search.html#docvalue-fields" title="Doc value fields"><code class="literal">docvalue_fields</code></a>
parameter to get values for selected fields. This can be a good
choice when returning a fairly small number of fields that support doc values,
such as keywords and dates.
</li>
<li class="listitem">
Use the <a class="xref" href="search-request-body.html#request-body-search-stored-fields" title="Stored Fields"><code class="literal">stored_fields</code></a> parameter to get the values for specific  stored fields. (Fields that use the <a class="xref" href="mapping-store.html" title="store"><code class="literal">store</code></a> mapping option.)
</li>
</ul>
</div>
<p>You can find more detailed information on each of these methods in the
following sections:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<a class="xref" href="run-a-search.html#source-filtering" title="Source filtering">Source filtering</a>
</li>
<li class="listitem">
<a class="xref" href="run-a-search.html#docvalue-fields" title="Doc value fields">Doc value fields</a>
</li>
<li class="listitem">
<a class="xref" href="run-a-search.html#stored-fields" title="Stored fields">Stored fields</a>
</li>
</ul>
</div>
<h3>
<a id="source-filtering"></a>Source filtering<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/search-fields.asciidoc">edit</a>
</h3>
<p>You can use the <code class="literal">_source</code> parameter to select what fields of the source are
returned. This is called <em>source filtering</em>.</p>
<details>
<summary class="title"><span class="strong strong"><strong>Example</strong></span></summary>
<div class="content">
<p>The following search API request sets the <code class="literal">_source</code> request body parameter to
<code class="literal">false</code>. The document source is not included in the response.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_search
{
  "_source": false,
  "query": {
    "term": {
      "user.id": "8a4f500d"
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/83.console"></div>
<p>To return only a subset of source fields, specify a wildcard (<code class="literal">*</code>) pattern in
the <code class="literal">_source</code> parameter. The following search API request returns the source for
only the <code class="literal">obj</code> field and its properties.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_search
{
  "_source": "obj.*",
  "query": {
    "term": {
      "user.id": "8a4f500d"
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/84.console"></div>
<p>You can also specify an array of wildcard patterns in the <code class="literal">_source</code> field. The
following search API request returns the source for only the <code class="literal">obj1</code> and
<code class="literal">obj2</code> fields and their properties.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_search
{
  "_source": [ "obj1.*", "obj2.*" ],
  "query": {
    "term": {
      "user.id": "8a4f500d"
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/85.console"></div>
<p>For finer control, you can specify an object containing arrays of <code class="literal">includes</code> and
<code class="literal">excludes</code> patterns in the <code class="literal">_source</code> parameter.</p>
<p>If the <code class="literal">includes</code> property is specified, only source fields that match one of
its patterns are returned. You can exclude fields from this subset using the
<code class="literal">excludes</code> property.</p>
<p>If the <code class="literal">includes</code> property is not specified, the entire document source is
returned, excluding any fields that match a pattern in the <code class="literal">excludes</code> property.</p>
<p>The following search API request returns the source for only the <code class="literal">obj1</code> and
<code class="literal">obj2</code> fields and their properties, excluding any child <code class="literal">description</code> fields.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_search
{
  "_source": {
    "includes": [ "obj1.*", "obj2.*" ],
    "excludes": [ "*.description" ]
  },
  "query": {
    "term": {
      "user.id": "8a4f500d"
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/86.console"></div>
</div>
</details>
<h3>
<a id="docvalue-fields"></a>Doc value fields<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/search-fields.asciidoc">edit</a>
</h3>
<p>You can use the <a class="xref" href="run-a-search.html#docvalue-fields" title="Doc value fields"><code class="literal">docvalue_fields</code></a> parameter to return
<a class="xref" href="doc-values.html" title="doc_values">doc values</a> for one or more fields in the search response.</p>
<p>Doc values store the same values as the <code class="literal">_source</code> but in an on-disk,
column-based structure that’s optimized for sorting and aggregations. Since each
field is stored separately, Elasticsearch only reads the field values that were requested
and can avoid loading the whole document <code class="literal">_source</code>.</p>
<p>Doc values are stored for supported fields by default. However, doc values are
not supported for <a class="xref" href="text.html" title="Text datatype"><code class="literal">text</code></a> or
<a href="/guide/en/elasticsearch/plugins/7.7/mapper-annotated-text-usage.html" class="ulink" target="_top"><code class="literal">text_annotated</code></a> fields.</p>
<details>
<summary class="title"><span class="strong strong"><strong>Example</strong></span></summary>
<div class="content">
<p>The following search request uses the <code class="literal">docvalue_fields</code> parameter to
retrieve doc values for the following fields:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
Fields with names starting with <code class="literal">my_ip</code>
</li>
<li class="listitem">
<code class="literal">my_keyword_field</code>
</li>
<li class="listitem">
Fields with names ending with <code class="literal">_date_field</code>
</li>
</ul>
</div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_search
{
  "query": {
    "match_all": {}
  },
  "docvalue_fields": [
    "my_ip*",                     <a id="CO32-1"></a><i class="conum" data-value="1"></i>
    {
      "field": "my_keyword_field" <a id="CO32-2"></a><i class="conum" data-value="2"></i>
    },
    {
      "field": "*_date_field",
      "format": "epoch_millis"    <a id="CO32-3"></a><i class="conum" data-value="3"></i>
    }
  ]
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/87.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO32-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Wildcard patten used to match field names, specified as a string.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO32-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>Wildcard patten used to match field names, specified as an object.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO32-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>With the object notation, you can use the <code class="literal">format</code> parameter to specify a
format for the field’s returned doc values. <a class="xref" href="date.html" title="Date datatype">Date fields</a> support a
<a class="xref" href="mapping-date-format.html" title="format">date <code class="literal">format</code></a>. <a class="xref" href="number.html" title="Numeric datatypes">Numeric fields</a> support a
<a href="https://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html" class="ulink" target="_top">DecimalFormat
pattern</a>. Other field datatypes do not support the <code class="literal">format</code> parameter.</p>
</td>
</tr>
</table>
</div>
</div>
</details>
<div class="tip admon">
<div class="icon"></div>
<div class="admon_content">
<p>You cannot use the <code class="literal">docvalue_fields</code> parameter to retrieve doc values for
nested objects. If you specify a nested object, the search returns an empty
array (<code class="literal">[ ]</code>) for the field. To access nested fields, use the
<a class="xref" href="search-request-body.html#request-body-search-inner-hits" title="Inner hits"><code class="literal">inner_hits</code></a> parameter’s <code class="literal">docvalue_fields</code>
property.</p>
</div>
</div>
<h3>
<a id="stored-fields"></a>Stored fields<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/search/search-fields.asciidoc">edit</a>
</h3>
<p>It’s also possible to store an individual field’s values by using the
<a class="xref" href="mapping-store.html" title="store"><code class="literal">store</code></a> mapping option. You can use the
<a class="xref" href="search-request-body.html#request-body-search-stored-fields" title="Stored Fields"><code class="literal">stored_fields</code></a> parameter to include
these stored values in the search response.</p>
</div>
<div class="navfooter">
<span class="prev">
<a href="search-your-data.html">« Search your data</a>
</span>
<span class="next">
<a href="near-real-time.html">Near real-time search »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
